Edenred Connect

Abstract

Parts of current document are extracted from RFC 6749 & http://openid.net/specs/openid-connect-core-1_0.html

The OAuth 2.0 authorization framework

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849.

OpenID Connect 1.0

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

Essentially, OAuth 2.0 framework allows Clients to obtain access to APIs, OpenID Connect 1.0 adds an authentication layer that allows Clients to identity a End-User.

Glossary

• Resource owner
  • An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
• Resource server
  • The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
• Client / Relying party (RP)
  • An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).
• Authorization server (AS)
  • The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Tokens

Tokens are credentials used to access a Client or a Resource. Three tokens are defined in OAuth 2.0/OpenID Connect 1.0:
Access tokens (OAuth 2.0) Refresh tokens (OAuth 2.0)
* Identity tokens (OpenID Connect 1.0)

Access tokens

Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server. The token may denote an identifier used to retrieve the authorization information (reference token) or may self-contain the authorization information in a verifiable manner (JWT).
Access tokens are used to access APIs.

Refresh tokens

Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner). Issuing a refresh token is optional at the discretion of the authorization server. If the authorization server issues a refresh token, it is included when issuing an access token.

ID tokens

The ID Token is part of OpenID Connect layer. Is is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims.

Authentication

Authentication can follow one of three paths: the Authorization Code Flow, the Implicit Flow , or the Hybrid Flow. The flows determine how the ID Token and Access Token are returned to the Client.
The characteristics of the three flows are summarized in the following non-normative table. The table is intended to provide some guidance on which flow to choose in particular contexts.

Authentication code flow

In the Authorization Code Flow, tokens are not revealed to User Agent, it requires a server side round trip to the Authorization server using client Id & client secret.
It goes through the following steps:
1. Client prepares an Authentication Request containing the desired request parameters.
2. Client sends the request to the Authorization Server.
3. Authorization Server authenticates the End-User.
4. Authorization Server obtains End-User Consent/Authorization.
5. Authorization Server sends the End-User back to the Client with an Authorization Code.
6. Client requests a response using the Authorization Code at the Token Endpoint.
7. Client receives a response that contains an ID Token and Access Token in the response body.
8. Client validates the ID token and retrieves the End-User's Subject Identifier.

Preparing & sending an Authentication Request

• scopeREQUIRED. OpenID Connect requests MUST contain the openid scope value. Other scope values MAY be present.

• response_typeREQUIRED. OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value is code.

• client_idREQUIRED. OAuth 2.0 Client Identifier valid at the Authorization Server.

• redirect_uriREQUIRED. Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described.

• stateRECOMMENDED. Opaque (random) value used to maintain state between the request and the callback. The value will be echoed in callback call.

• nonceOPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value will be echoed in ID Token.REQUIRED in implicit flow.

• ui_localesOPTIONAL. End-User's preferred languages for the user interface.

• acr_valuesOPTIONAL. Requested Authentication Context Class Reference values. It allows to pass additional authentication related information - there are also values with special meaning:

  • tenant:name_of_tenant can be used to pass a tenant name

The request takes form of a redirection to:
```http
GET /idsrv/connect/authorize HTTP/1.1
Host: sso.auth-sandbox.api.edenred.com
Content-Type: application/x-www-form-urlencoded

client_id=&response_type=code&scope=openid+&redirect_uri=&state=&nonce=&acr_values=tenant%3A&ui_locales=```

To associate the authentication session request & response and mitigate replay attack, it is recommended to store in an HttpOnly cookie the state and nonce parameters and to validate returned values against cookie values. Concerning nonce parameter, a cryptographic hash (e.g. SHA-256 hash) should be stored in the cookie.

Authenticating End-User and obtaining consent

Authorization server displays login form. This form can be customized by Client.

If authentication is successful, Authorization server asks for End-User consent about sharing information with Client. Requiring consent can enabled/disabled by Client.

Authorization sends a successful response to User-Agent. This response contains a redirection to the callback uri specified in the request.

HTTP/1.1 302 Found

Location: https://redirect.uri.tld/callback?code=<code>&state=<state_from_request>

Client must extract code on server-side and request tokens from Authorization server token endpoint using the code. It also can check that state parameter is consistent with stored one.

POST /idsrv/connect/token HTTP/1.1
Host: sso.auth-sandbox.api.edenred.com
Content-Type: application/x-www-form-urlencoded

client_id=<clientId>&client_secret=<clientSecret>&grant_type=authorization_code&code=<code>&redirect_uri=<redirectUri>&acr_values=tenant%3A<tenant>

The Authorization server token endpoint response contains requested tokens:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

  {
   "access_token": "<accessToken>",
   "token_type": "Bearer",
   "refresh_token": "<refreshToken>",
   "expires_in": 3600,
   "id_token": "<idToken>"
  }

The signature of received token must be validated. If client application has access to cryptographic librairies, it can make this verification locally using signing public key from AS JWKS endpoint (URI is available from discovery/well knownd document); otherwise AS provides a validation endpoint (/connect/identitytokenvalidation).
To enable federated signing out process, client application must link its own session to AS session identifier provided in token.

Implicit flow

The implicit flow allows to receive token in an unique round trip to Authorization server. Tokens are received as part of the redirection uri (using query string parameters or uri fragments). It is particularly suitable for client-side clients. This flow doesn't provide long-lived tokens (refresh tokens).

Hybrid flow

To take advantage of both implicit flow and authorization code flow (a single round trip regarding the former, better security and refresh tokens in the latter), AS provides hybrid flow. In this flow, client application can choose to receive identity token, access token and/or code during the first round trip and uses additional requests to AS to retrieve refresh tokens and new access tokens.

Signing out

The AS supports the front channel logout feature (http://openid.net/specs/openid-connect-frontchannel-1_0.html). This feature allows to keep session state consistent between AS and RP, i.e. when a user signs out from an application, AS sends signing out requests to all others applications that use SSO system. RPs supporting HTTP-based logout register a logout URI with the OP as part of their client registration. The signout flow goes through the following steps:
RP initiate logout process by redirecting user to AS end session endpoint. If required, RP renders lougout confirmation prompt
If user confirms, user is loged out from AS and logger-out confirmation page is displayed In logger-out confirmation page, AS includes iframe to RP logout URI

The RP logout URI should take two query string parameters:
iss: Identifer of token issuer sid: Session identifier

RP logout request

GET /idsrv/connect/endsession HTTP/1.1
Host: sso.auth-sandbox.api.edenred.com
Content-Type: application/x-www-form-urlencoded

id_token_hint=<idToken>&post_logout_redirect_uri=<postLogoutRedirectUri>

Token revocation

Revoking a token removes it from AS token store and avoid further use. Revocation is only available on reference tokens and is defined in RFC 7009 (https://tools.ietf.org/html/rfc7009).
Supported parameters:
token (required): the token to revoke token_type_hint: either access_token or refresh_token

Token revocation endpoint requires authentication using client id and client secret either in request body or as a basic authentication request header.
These two requests are equivalent:

POST /idsrv/connect/revocation HTTP/1.1
Host: sso.auth-sandbox.api.edenred.com
Content-Type: application/x-www-form-urlencoded

client_id=<clientId>&client_secret=<clientSecret>&token=SyIOqEytp8S55ncIZbOv&token_type_hint=refresh_token

POST /idsrv/connect/revocation HTTP/1.1
Host: sso.auth-sandbox.api.edenred.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1lPGNsaWVudElkPjo8Y2xpZW50U2VjcmV0Pg==

token=SyIOqEytp8S55ncIZbOv&token_type_hint=refresh_token